home *** CD-ROM | disk | FTP | other *** search
/ Megahits 5 / Megahits 5 (1994)(GTI - Rhein-Main-Soft)(DE)(Disc 2 of 2)[!].iso / archive / show / superview_lib6_3.lha / superview-lib / Docs / Reference_ENG.doc < prev    next >
Text File  |  1994-06-06  |  27KB  |  1,321 lines
  1.  
  2.    $VER: Reference_ENG.doc V6.3 (4.6.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.    Andreas R. Kleinert
  9.    Grube Hohe Grethe 23
  10.    D-57074 Siegen
  11.    Germany
  12.  
  13.  
  14.    Please note the version-dependencies :
  15.  
  16.     superview.library       SVObjects      SVDrivers     SVOperators
  17.  
  18.     Version 1           -          -         -
  19.     Version 2           Version 1      -         -
  20.     Version 3-6        Version 1,2      Version 1     -
  21.  
  22.  
  23.    Request at least :  V2+    for SVObjects
  24.                V3+    for SVDrivers
  25.                V4+    for bug-fixed ClipBoard-Support
  26.                   with the supplied SVObjects
  27.                V5+    for bug-fixed GfxBuffer-Functions
  28.                V6+    for working GfxBuffer-Writing
  29.                   with the supplied SVObjects
  30.  
  31.  
  32.    Here is a listing of all currently available functions of the
  33.    superview.library in an Autodoc-like style of description :
  34.  
  35.     SVL_AllocHandle        ; since Version 1
  36.     SVL_FreeHandle
  37.     SVL_CloseDisplay
  38.     SVL_FreeResources
  39.     SVL_SuperView
  40.     SVL_SuperWrite
  41.     SVL_InitHandleAsDOS
  42.     SVL_InitHandleAsClip
  43.     SVL_SetWriteType
  44.     SVL_SetWindowIDCMP
  45.     SVL_SetWindowFlags
  46.     SVL_SetScreenType
  47.     SVL_GetWindowAddress
  48.     SVL_GetScreenAddress
  49.     SVL_GetErrorString
  50.     SVL_SetWriteScreen
  51.     SVL_SetWriteName
  52.     SVL_FileInfoRequest
  53.            ; no functions added in Version 2
  54.     SVL_GetGlobalDriver       ; since Version 3
  55.     SVL_SetGlobalDriver
  56.     SVL_ReadToGfxBuffer
  57.     SVL_GetGfxBuffer
  58.     SVL_SetGfxBuffer
  59.     SVL_DisplayGfxBuffer
  60.            ; no functions added in Version 4
  61.            ; no functions added in Version 5
  62.     SVL_GetSVObjectList       ; since Version 6
  63.     SVL_GetSVDriverList
  64.     SVL_FreeSVObjectList
  65.     SVL_FreeSVDriverList
  66.  
  67. -----------------------------------------------------------------------------
  68.    Functions available since Version 1 - 2 :
  69. -----------------------------------------------------------------------------
  70.  
  71.    NAME
  72.     SVL_AllocHandle
  73.  
  74.    SYNOPSIS
  75.  
  76.     APTR SVL_AllocHandle(APTR future)
  77.     D0   -$1e         A1
  78.  
  79.    FUNCTION
  80.  
  81.     Allocates a handle for accessing a Graphic via SVObjects.
  82.  
  83.    INPUT(S)
  84.  
  85.     future - always NULL yet
  86.  
  87.    RESULT
  88.  
  89.     A pointer to a new allocated Handle or NULL, if allocation failed.
  90.  
  91.    WARNING
  92.  
  93.     Test, if the result was NULL, or not !
  94.  
  95.    BUGS
  96.  
  97.     -
  98.  
  99.    SINCE
  100.  
  101.     ... version 1 of the superview.library.
  102.  
  103.    SEE ALSO
  104.  
  105.     SVL_FreeResources, SVL_FreeHandle
  106.  
  107. -----------------------------------------------------------------------------
  108.  
  109.    NAME
  110.     SVL_FreeHandle
  111.  
  112.    SYNOPSIS
  113.  
  114.     VOID SVL_FreeHandle(APTR handle)
  115.     D0   -$24        A1
  116.  
  117.    FUNCTION
  118.  
  119.        Stops showing, frees all Resources and delocates a Handle, which has
  120.        been allocated with SVL_AllocHandle before.
  121.  
  122.  
  123.        For programmers of SVObjects :
  124.  
  125.        Note, that this functions calls
  126.  
  127.       SVL_CloseDisplay(SVHandle);
  128.       SVL_FreeResources(SVHandle);
  129.  
  130.        for internal SVObjects and
  131.  
  132.       SVO_FreeHandle(SVHandle->ah_SVHandle);
  133.  
  134.       CloseLibrary((APTR) SVObjectBase);
  135.  
  136.        for external SVObjects.
  137.        So do not forget to do the SVO_CloseDisplay() and SVO_FreeResources()
  138.        calls inside SVO_FreeHandle().
  139.        Otherwise memory might be lost.
  140.  
  141.    INPUT(S)
  142.  
  143.     handle - a valid handle
  144.  
  145.    RESULT
  146.  
  147.     -
  148.  
  149.    BUGS
  150.  
  151.     This function was buggy for external SVObjects (never closed, memory
  152.     loss) upto V2.4.
  153.  
  154.    SINCE
  155.  
  156.     ... version 1 of the superview.library.
  157.  
  158.    SEE ALSO
  159.  
  160.     SVL_AllocHandle, SVL_CloseDisplay, SVL_FreeResources
  161.  
  162. -----------------------------------------------------------------------------
  163.  
  164.    NAME
  165.     SVL_CloseDisplay
  166.  
  167.    SYNOPSIS
  168.  
  169.     VOID SVL_CloseDisplay(APTR handle)
  170.     D0   -$2a          A1
  171.  
  172.    FUNCTION
  173.  
  174.     Stops showing the Graphic, indentified by the handle.
  175.     The Display-Screen is closed, but no Resources are given free.
  176.  
  177.    INPUT(S)
  178.  
  179.     handle - a valid handle
  180.  
  181.    RESULT
  182.  
  183.     -
  184.  
  185.    BUGS
  186.  
  187.     -
  188.  
  189.    SINCE
  190.  
  191.     ... version 1 of the superview.library.
  192.  
  193.    SEE ALSO
  194.  
  195.     SVL_FreeResources, SVL_FreeHandle
  196.  
  197. -----------------------------------------------------------------------------
  198.  
  199.    NAME
  200.     SVL_FreeResources
  201.  
  202.    SYNOPSIS
  203.  
  204.     VOID SVL_FreeResources(APTR handle)
  205.     D0   -$30           A1
  206.  
  207.    FUNCTION
  208.  
  209.     Frees all resources belonging to the specific Graphic,
  210.     indentified by the handle, which are not needed to just show it.
  211.     The Display will not be closed.
  212.  
  213.     Note, that SVL_FileInfoRequest() will no longer work, then
  214.     ("No file loaded" or similar request appears).
  215.  
  216.    INPUT(S)
  217.  
  218.     handle - a valid handle
  219.  
  220.    RESULT
  221.  
  222.     -
  223.  
  224.    BUGS
  225.  
  226.     -
  227.  
  228.    SINCE
  229.  
  230.     ... version 1 of the superview.library.
  231.  
  232.    SEE ALSO
  233.  
  234.     SVL_AllocHandle, SVL_CloseDisplay, SVL_FreeHandle
  235.  
  236. -----------------------------------------------------------------------------
  237.  
  238.    NAME
  239.     SVL_SuperView
  240.  
  241.    SYNOPSIS
  242.  
  243.     ULONG SVL_SuperView(APTR handle, char *filename)
  244.     D0    -$36        A1         A2
  245.  
  246.    FUNCTION
  247.  
  248.     Loads and shows the Graphic described by FileName.
  249.     The handle is initialized and the fitting SVObject is opened
  250.     and accessed for showing the Graphic.
  251.  
  252.     Showing can be stopped either via full delocation of the handle
  253.     or via Closing the Display with SVL_CloseDisplay.
  254.  
  255.    INPUT(S)
  256.  
  257.     handle     - a valid handle
  258.     filename - a valid AmigaDOS FilePath and -Name
  259.  
  260.    RESULT
  261.  
  262.     NULL or an adequate SVERR-Errorcode.
  263.  
  264.    BUGS
  265.  
  266.     -
  267.  
  268.    SINCE
  269.  
  270.     ... version 1 of the superview.library.
  271.  
  272.    SEE ALSO
  273.  
  274.     SVL_AllocHandle, SVL_CloseDisplay, SVL_FreeHandle
  275.  
  276. -----------------------------------------------------------------------------
  277.  
  278.    NAME
  279.     SVL_SuperWrite
  280.  
  281.    SYNOPSIS
  282.  
  283.     ULONG SVL_SuperWrite(APTR handle, APTR source_handle)
  284.     D0    -$3c         A1       A2
  285.  
  286.    FUNCTION
  287.  
  288.     Before Version 3 a Graphic had to be loaded AND showed via
  289.     SVL_SuperView : No separate reading and showing calls were done.
  290.     For writing - that means : converting - a Graphic, you at first
  291.     have to display, then to save it. Use the following order :
  292.  
  293.     (But check the "result" value AFTER EACH function call, like this
  294.      has been done in the example SourceCodes ...)
  295.  
  296.     source_handle = SVL_AllocHandle(N);
  297.     /* result     = SVL_InitHandleAsDOS(source_handle, N); */ /* default */
  298.     result          = SVL_SetWindowIDCMP(source_handle,
  299.                     IDCMP_MOUSEBUTTONS | IDCMP_VANILLAKEY, N)))
  300.     result          = SVL_SetScreenType(source_handle, CUSTOMSCREEN, N)))
  301.     result          = SVL_SuperView(source_handle, source_filename)))
  302.     result          = SVL_GetScreenAddress(source_handle, &sv_screen, N)))
  303.     result          = SVL_GetWindowAddress(source_handle, &sv_window, N)))
  304.  
  305.     dest_handle   = SVL_AllocHandle(N);
  306.     /* result     = SVL_InitHandleAsDOS(dest_handle, N); */ /* default */
  307.     result          = SVL_SetWriteType(dest_handle, dest_type, N)))
  308.     result          = SVL_SetWriteName(dest_handle, dest_filename, N)))
  309.     result          = SVL_SetWriteScreen(dest_handle, sv_screen, N)))
  310.     result          = SVL_SuperWrite(dest_handle, source_handle);
  311.     SVL_FreeHandle(dest_handle);
  312.  
  313.     SVL_FreeHandle(source_handle);
  314.  
  315.  
  316.     Since Version 3 it is also possible to save the contents of
  317.     SV_GfxBuffers, so that not necessarily a Screen has to be the
  318.     source for writing to Disk/ClipBoard (or to whatever).
  319.     Not all SVObjects may necessarily support this (return-code
  320.     becomes SVERR_ACTION_NOT_SUPPORTED).
  321.     But since Version 6 all of the supplied SVObjects (those which come
  322.     with superview.library and contain Write-Support) allow this.
  323.     So, if you request at least V6+, the likelihood will be with you ...
  324.  
  325.     All available values for dest_type can be found in the specific
  326.     SVObject-List in SuperViewBase.
  327.     The values WILL change with every re-initialization of
  328.     superview.library, so update them with every new opening
  329.     (read them from the SVObject-List inside SuperViewBase or use the
  330.      new functions, which have been introduced with V6).
  331.     Only ILBM.svobject and ACBM.svobject (and the internal Datatype-
  332.     svobject, which cannot be used for saving, anyway) keep the same
  333.     values for compatibility reasons, but since two of these are now
  334.     external you might not be sure, if they are available
  335.     (which means : actually in "LIBS:svobjects") or not ...
  336.  
  337.    INPUT(S)
  338.  
  339.     handle          - a valid handle          (used for Write Access)
  340.     source_handle - an other valid handle (used for Read Access)
  341.  
  342.    RESULT
  343.  
  344.     NULL or an adequate SVERR-Errorcode.
  345.  
  346.    BUGS
  347.  
  348.     -
  349.  
  350.    SINCE
  351.  
  352.     ... version 1 of the superview.library.
  353.  
  354.    SEE ALSO
  355.  
  356.  
  357.  
  358.     SVL_AllocHandle, SVL_FreeHandle
  359.  
  360. -----------------------------------------------------------------------------
  361.  
  362.    NAME
  363.     SVL_InitHandleAsDOS
  364.  
  365.    SYNOPSIS
  366.  
  367.     ULONG SVL_InitHandleAsDOS(APTR handle, APTR future)
  368.     D0    -$42          A1           A2
  369.  
  370.    FUNCTION
  371.  
  372.     Initializes a Handle for AmigaDOS access, so that the given
  373.     AmigaDOS FileNames are used.
  374.     Another possibility is sometimes to initialize Handles
  375.     for ClipBoard Access (depending on the specific SVObject,
  376.     e.g. IFF-ILBM).
  377.  
  378.    INPUT(S)
  379.  
  380.     handle - a valid handle
  381.     future - always NULL yet
  382.  
  383.    RESULT
  384.  
  385.     NULL or an adequate SVERR-Errorcode.
  386.  
  387.    BUGS
  388.  
  389.     During V2.4 upto V3.8 this was done automatically ALWAYS.
  390.     This was fixed in V4.1
  391.     See BUGS under SVL_InitHandleAsClip.
  392.  
  393.    SINCE
  394.  
  395.     ... version 1 of the superview.library.
  396.  
  397.    SEE ALSO
  398.  
  399.  
  400.  
  401.     SVL_InitHandleAsClip
  402.  
  403. -----------------------------------------------------------------------------
  404.  
  405.    NAME
  406.     SVL_InitHandleAsClip
  407.  
  408.    SYNOPSIS
  409.  
  410.     ULONG SVL_InitHandleAsClip(APTR handle, APTR future)
  411.     D0    -$48           A1        A2
  412.  
  413.    FUNCTION
  414.  
  415.     Initializes a Handle for ClipBoard access, so that the (possibly)
  416.     given AmigaDOS FileNames are ignored.
  417.     The nearly always used possibility is to initialize Handles
  418.     for AmigaDOS Access (supported by ALL SVObjects).
  419.  
  420.    INPUT(S)
  421.  
  422.     handle - a valid handle
  423.     future - always NULL yet
  424.  
  425.    RESULT
  426.  
  427.     NULL or an adequate SVERR-Errorcode.
  428.  
  429.    BUGS
  430.  
  431.     From 2.4 to 3.8 this function-call was useless, since
  432.     superview.library blocked all medias other than
  433.     AKO_MEDIUM_DISK for external SVObjects :
  434.     For reading calls, this resulted in a "file not found" message
  435.     from superview.library, for writing calls, this resulted in an
  436.     empty filename string, which caused the SVObject to reject the
  437.     disk access (other accesses were not set correctly).
  438.     This was fixed in 4.1, by using the SVO_SetAccessMode() function
  439.     with the right parameters now and by using the "future" parameter
  440.     of SVO_CheckFileType() - only when using other media than
  441.     AKO_MEDIUM_DISK - as a pointer to an additional SVOCheckFileInfo
  442.     structure now.
  443.     This is 100% compatible, since superview.library has always set
  444.     this value to NULL, so that older SVObjects will simply ignore
  445.     this pointer and newer versions will only interpret it, if it's
  446.     not NULL.
  447.  
  448.    SINCE
  449.  
  450.     ... version 1 of the superview.library. (request V4+)
  451.  
  452.    SEE ALSO
  453.  
  454.     SVL_InitHandleAsDOS
  455.  
  456. -----------------------------------------------------------------------------
  457.  
  458.    NAME
  459.     SVL_SetWriteType
  460.  
  461.    SYNOPSIS
  462.  
  463.     ULONG SVL_SetWriteType(APTR handle, ULONG write_type, APTR future)
  464.     D0    -$4e           A1        A2              A3
  465.  
  466.    FUNCTION
  467.  
  468.     Sets the write_type for a SVL_SuperWrite() call.
  469.     See description there and example SourceCodes for more and
  470.     detailed information.
  471.  
  472.    INPUT(S)
  473.  
  474.     handle       - a valid handle
  475.     write_type - a valid temporary SubTypeCode from the SVObject-List
  476.     future       - always NULL yet
  477.  
  478.    RESULT
  479.  
  480.     NULL or an adequate SVERR-Errorcode.
  481.  
  482.    BUGS
  483.  
  484.     -
  485.  
  486.    SINCE
  487.  
  488.     ... version 1 of the superview.library.
  489.  
  490.    SEE ALSO
  491.  
  492.     SVL_SuperWrite
  493.  
  494. -----------------------------------------------------------------------------
  495.  
  496.    NAME
  497.     SVL_SetWindowIDCMP
  498.  
  499.    SYNOPSIS
  500.  
  501.     ULONG SVL_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  502.     D0    -$54         A1          A2       A3
  503.  
  504.    FUNCTION
  505.  
  506.     Sets the default IDCMP-Flags for a SVL_SuperView() call.
  507.     While displaying, the Address of the Window can be get via the
  508.     SVL_GetWindowAddress() function.
  509.     See description there and example SourceCodes for more and
  510.     detailed information.
  511.  
  512.    INPUT(S)
  513.  
  514.     handle - a valid handle
  515.     idcmp  - a valid number of IDCMP-Flags
  516.     future - always NULL yet
  517.  
  518.    RESULT
  519.  
  520.     NULL or an adequate SVERR-Errorcode.
  521.  
  522.    BUGS
  523.  
  524.     -
  525.  
  526.    SINCE
  527.  
  528.     ... version 1 of the superview.library.
  529.  
  530.    SEE ALSO
  531.  
  532.     SVL_SuperView
  533.  
  534. -----------------------------------------------------------------------------
  535.  
  536.    NAME
  537.     SVL_SetWindowFlags
  538.  
  539.    SYNOPSIS
  540.  
  541.     ULONG SVL_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  542.     D0    -$5a         A1          A2       A3
  543.  
  544.    FUNCTION
  545.  
  546.     Sets the default Window-Flags for a SVL_SuperView() call.
  547.     While displaying, the Address of the Window can be get via the
  548.     SVL_GetWindowAddress() function.
  549.     See description there and example SourceCodes for more and
  550.     detailed information.
  551.  
  552.    INPUT(S)
  553.  
  554.     handle - a valid handle
  555.     flags  - a valid number of Window-Flags
  556.     future - always NULL yet
  557.  
  558.    RESULT
  559.  
  560.     NULL or an adequate SVERR-Errorcode.
  561.  
  562.    BUGS
  563.  
  564.     -
  565.  
  566.    SINCE
  567.  
  568.     ... version 1 of the superview.library.
  569.  
  570.    SEE ALSO
  571.  
  572.     SVL_SuperView
  573.  
  574. -----------------------------------------------------------------------------
  575.  
  576.    NAME
  577.     SVL_SetScreenType
  578.  
  579.    SYNOPSIS
  580.  
  581.     ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future)
  582.     D0    -$60        A1         A2      A3
  583.  
  584.    FUNCTION
  585.  
  586.     Sets the default Screen-Type for a SVL_SuperView() call.
  587.     While displaying, the Address of the Screen can be get via the
  588.     SVL_GetScreenAddress() function.
  589.     See description there and example SourceCodes for more and
  590.     detailed information.
  591.  
  592.    INPUT(S)
  593.  
  594.     handle - a valid handle
  595.     type   - a valid ScreenType value (e.g. CUSTOMSCREEN)
  596.     future - always NULL yet
  597.  
  598.    RESULT
  599.  
  600.     NULL or an adequate SVERR-Errorcode.
  601.  
  602.    BUGS
  603.  
  604.     -
  605.  
  606.    SINCE
  607.  
  608.     ... version 1 of the superview.library.
  609.  
  610.    SEE ALSO
  611.  
  612.     SVL_SuperView
  613.  
  614. -----------------------------------------------------------------------------
  615.  
  616.    NAME
  617.     SVL_GetWindowAddress
  618.  
  619.    SYNOPSIS
  620.  
  621.     ULONG SVL_GetWindowAddress(APTR handle, struct Window **window,
  622.     D0    -$66           A1        A2
  623.  
  624.                    APTR future)
  625.                    A3
  626.  
  627.    FUNCTION
  628.  
  629.     While displaying, the Address of the DisplayWindow can be get
  630.     via this function.
  631.     See description there and example SourceCodes for more and
  632.     detailed information.
  633.  
  634.    INPUT(S)
  635.  
  636.     handle - a valid handle
  637.     window - a valid address of a Window-Pointer
  638.     future - always NULL yet
  639.  
  640.    RESULT
  641.  
  642.     NULL or an adequate SVERR-Errorcode.
  643.  
  644.    BUGS
  645.  
  646.     -
  647.  
  648.    SINCE
  649.  
  650.     ... version 1 of the superview.library.
  651.  
  652.    SEE ALSO
  653.  
  654.     SVL_SuperWrite
  655.  
  656. -----------------------------------------------------------------------------
  657.  
  658.    NAME
  659.     SVL_GetScreenAddress
  660.  
  661.    SYNOPSIS
  662.  
  663.     ULONG SVL_GetScreenAddress(APTR handle, struct Screen **screen,
  664.     D0    -$66           A1        A2
  665.  
  666.                    APTR future)
  667.                    A3
  668.  
  669.    FUNCTION
  670.  
  671.     While displaying, the Address of the DisplayScreen can be get
  672.     via this function.
  673.     See description there and example SourceCodes for more and
  674.     detailed information.
  675.  
  676.    INPUT(S)
  677.  
  678.     handle - a valid handle
  679.     screen - a valid address of a Screen-Pointer
  680.     future - always NULL yet
  681.  
  682.    RESULT
  683.  
  684.     NULL or an adequate SVERR-Errorcode.
  685.  
  686.    BUGS
  687.  
  688.     -
  689.  
  690.    SINCE
  691.  
  692.     ... version 1 of the superview.library.
  693.  
  694.    SEE ALSO
  695.  
  696.     SVL_SuperWrite
  697.  
  698. -----------------------------------------------------------------------------
  699.  
  700.    NAME
  701.     SVL_GetErrorString
  702.  
  703.    SYNOPSIS
  704.  
  705.     char * SVL_GetErrorString(ULONG error_code)
  706.     D0    -$72          A1
  707.  
  708.    FUNCTION
  709.  
  710.     Returns the Error Message for a specific Error Code, returned
  711.     by any function of the superview.library.
  712.  
  713.    INPUT(S)
  714.  
  715.     error_code - any SVERR Error Code
  716.  
  717.    RESULT
  718.  
  719.     read-only pointer to a SVERR Error String
  720.  
  721.    BUGS
  722.  
  723.     -
  724.  
  725.    SINCE
  726.  
  727.     ... version 1 of the superview.library.
  728.  
  729.    SEE ALSO
  730.  
  731.     -
  732.  
  733. -----------------------------------------------------------------------------
  734.  
  735.    NAME
  736.     SVL_SetWriteScreen
  737.  
  738.    SYNOPSIS
  739.  
  740.     ULONG SVL_SetWriteScreen(APTR handle, struct Screen *screen,
  741.     D0    -$78         A1          A2
  742.  
  743.                  APTR future)
  744.                  A3
  745.  
  746.    FUNCTION
  747.  
  748.     Sets the Source Screen for a SVL_SuperWrite() call.
  749.     See description there and example SourceCodes for more and
  750.     detailed information.
  751.  
  752.     This will overwrite a previously done SVL_SetGfxBuffer() call.
  753.  
  754.    INPUT(S)
  755.  
  756.     handle - a valid handle
  757.     screen - a valid pointer to an opened Screen
  758.     future - always NULL yet
  759.  
  760.    RESULT
  761.  
  762.     NULL or an adequate SVERR-Errorcode.
  763.  
  764.    BUGS
  765.  
  766.     -
  767.  
  768.    SINCE
  769.  
  770.     ... version 1 of the superview.library.
  771.  
  772.    SEE ALSO
  773.  
  774.     SVL_SuperWrite
  775.  
  776. -----------------------------------------------------------------------------
  777.  
  778.    NAME
  779.     SVL_SetWriteName
  780.  
  781.    SYNOPSIS
  782.  
  783.     ULONG SVL_SetWriteName(APTR handle, ULONG write_name, APTR future)
  784.     D0    -$7e           A1        A2              A3
  785.  
  786.    FUNCTION
  787.  
  788.     Sets the write_name for a SVL_SuperWrite() call.
  789.     See description there and example SourceCodes for more and
  790.     detailed information.
  791.  
  792.    INPUT(S)
  793.  
  794.     handle       - a valid handle
  795.     write_name - a valid AmigaDOS FilePath and -Name description
  796.     future       - always NULL yet
  797.  
  798.  
  799.    RESULT
  800.  
  801.     NULL or an adequate SVERR-Errorcode.
  802.  
  803.    BUGS
  804.  
  805.     -
  806.  
  807.    SINCE
  808.  
  809.     ... version 1 of the superview.library.
  810.  
  811.    SEE ALSO
  812.  
  813.     SVL_SuperWrite
  814.  
  815. -----------------------------------------------------------------------------
  816.  
  817.    NAME
  818.     SVL_FileInfoRequest
  819.  
  820.    SYNOPSIS
  821.  
  822.     ULONG SVL_FileInfoRequest(APTR handle, struct Window *window,
  823.     D0    -$84          A1           A2
  824.  
  825.                   APTR future)
  826.                   A3
  827.  
  828.    FUNCTION
  829.  
  830.     Pops up an Info-Requester with more or less detailed information
  831.     on the currently loaded Graphic.
  832.     A window pointer may be given to select the place to pop it up.
  833.  
  834.     Note, that this function will fail, if you already called
  835.     SVL_FreeResources() (might result in a "No file loaded" message) !
  836.  
  837.    INPUT(S)
  838.  
  839.     handle - a valid handle
  840.     window - a valid Window Pointer or NULL
  841.     future - always NULL yet
  842.  
  843.    RESULT
  844.  
  845.     NULL or an adequate SVERR-Errorcode.
  846.  
  847.    BUGS
  848.  
  849.     None known, but :
  850.     For non-internal SVObjects SVO_FileInfoRequest() is called, thus
  851.     if this one is buggy, ...
  852.  
  853.     The Easy-Requester (or whatever else it is) will usually be attached
  854.     to IntuitionBase->ActiveWindow, if window is NULL.
  855.     This may cause problems sometimes, so always specify a WindowPtr,
  856.     if possible !
  857.  
  858.    SINCE
  859.  
  860.     ... version 1 of the superview.library.
  861.  
  862.    SEE ALSO
  863.  
  864.     -
  865.  
  866. -----------------------------------------------------------------------------
  867.    Functions added with Version 3 - 5 :
  868. -----------------------------------------------------------------------------
  869.  
  870.    NAME
  871.     SVL_GetGlobalDriver
  872.  
  873.    SYNOPSIS
  874.  
  875.     ULONG SVL_GetGlobalDriver(struct SVD_DriverNode **driver,
  876.     D0    -$8a          A1
  877.  
  878.                   ULONG future)
  879.                   A2
  880.  
  881.    FUNCTION
  882.  
  883.     Gets the Global Default ScreenDriver (SVDriver) from the
  884.     specific field of SuperViewBase.
  885.  
  886.     Always use this function. Do not access SuperViewBase directly !
  887.  
  888.    INPUT(S)
  889.  
  890.     driver - a pointer to a SVD_DriverNode pointer
  891.     future - always NULL yet
  892.  
  893.  
  894.    RESULT
  895.  
  896.     NULL or an adequate SVERR-Errorcode.
  897.  
  898.    BUGS
  899.  
  900.     -
  901.  
  902.    SINCE
  903.  
  904.     ... version 3 of the superview.library.
  905.  
  906.    SEE ALSO
  907.  
  908.     SVL_SetGlobalDriver()
  909.  
  910. -----------------------------------------------------------------------------
  911.  
  912.    NAME
  913.     SVL_SetGlobalDriver
  914.  
  915.    SYNOPSIS
  916.  
  917.     ULONG SVL_SetGlobalDriver(struct SVD_DriverNode *driver,
  918.     D0    -$90          A1
  919.  
  920.                   ULONG future)
  921.                   A2
  922.  
  923.    FUNCTION
  924.  
  925.     Sets a new Global Default ScreenDriver (SVDriver) in the
  926.     specific field of SuperViewBase.
  927.  
  928.     Always use this function. Do not access SuperViewBase directly !
  929.  
  930.    INPUT(S)
  931.  
  932.     driver - a pointer to a SVD_DriverNode
  933.     future - always NULL yet
  934.  
  935.    RESULT
  936.  
  937.     NULL or an adequate SVERR-Errorcode.
  938.  
  939.    BUGS
  940.  
  941.     -
  942.  
  943.    SINCE
  944.  
  945.     ... version 3 of the superview.library.
  946.  
  947.    SEE ALSO
  948.  
  949.     SVL_GetGlobalDriver()
  950.  
  951. -----------------------------------------------------------------------------
  952.  
  953.    NAME
  954.     SVL_ReadToGfxBuffer
  955.  
  956.    SYNOPSIS
  957.  
  958.     ULONG SVL_ReadToGfxBuffer(APTR handle, char *filename)
  959.     D0    -$96          A1           A2
  960.  
  961.    FUNCTION
  962.  
  963.     Reads the graphic file - specified with filename - into
  964.     a SV_GfxBuffer structure.
  965.  
  966.     Access to this structure can be managed via SVL_GetGfxBuffer().
  967.  
  968.     The combination SVL_ReadToGfxBuffer() and SVL_DisplayGfxBuffer()
  969.     has the same effect as a call to SVL_SuperView().
  970.     But note, that GfxBuffer-functions only work with Version 2
  971.     SVObjects, while SVL_SuperView() also fits to Version 1 SVObjects.
  972.     Internally, the result is the same, anyway.
  973.  
  974.    INPUT(S)
  975.  
  976.     handle     - a valid handle
  977.     filename - a valid AmigaDOS FilePath and -Name
  978.  
  979.    RESULT
  980.  
  981.     NULL or an adequate SVERR-Errorcode.
  982.  
  983.    BUGS
  984.  
  985.     This function was broken from V3.x to V4.x !
  986.  
  987.    SINCE
  988.  
  989.     ... version 3 of the superview.library. (request V5+)
  990.  
  991.    SEE ALSO
  992.  
  993.     SVL_GetGfxBuffer(), SVL_DisplayGfxBuffer()
  994.  
  995. -----------------------------------------------------------------------------
  996.  
  997.    NAME
  998.     SVL_GetGfxBuffer
  999.  
  1000.    SYNOPSIS
  1001.  
  1002.     ULONG SVL_GetGfxBuffer(APTR handle, struct SV_GfxBuffer **buffer,
  1003.     D0    -$9c           A1        A2
  1004.  
  1005.                    ULONG future)
  1006.                    A3
  1007.  
  1008.  
  1009.    FUNCTION
  1010.  
  1011.     For READ accessing the SV_GfxBuffer structure, which has been
  1012.     created with SVL_ReadGfxBuffer() before.
  1013.  
  1014.     Do not change, write to or free this structure by hand.
  1015.     Nevertheless you may create your own structures.
  1016.  
  1017.    INPUT(S)
  1018.  
  1019.     handle - a valid handle
  1020.     buffer - a pointer to a valid SV_GfxBuffer pointer
  1021.     future - always NULL yet
  1022.  
  1023.  
  1024.    RESULT
  1025.  
  1026.     NULL or an adequate SVERR-Errorcode.
  1027.  
  1028.    BUGS
  1029.  
  1030.     This function was broken from V3.x to V4.x !
  1031.  
  1032.    SINCE
  1033.  
  1034.     ... version 3 of the superview.library. (request V5+)
  1035.  
  1036.    SEE ALSO
  1037.  
  1038.     SVL_ReadGfxBuffer(), SVL_DisplayGfxBuffer()
  1039.  
  1040. -----------------------------------------------------------------------------
  1041.  
  1042.    NAME
  1043.     SVL_SetGfxBuffer
  1044.  
  1045.    SYNOPSIS
  1046.  
  1047.     ULONG SVL_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  1048.     D0    -$a2           A1        A2
  1049.  
  1050.                    ULONG future)
  1051.                    A3
  1052.  
  1053.  
  1054.    FUNCTION
  1055.  
  1056.     This functions allows you to pass your own, self-created
  1057.     SV_GfxBuffer structures or also structures accessed via
  1058.     SVL_GetGfxBuffer() to the library.
  1059.  
  1060.     This will overwrite a previously done SVL_SetWriteScreen() call.
  1061.  
  1062.     The next SVL_SuperWrite() call will use the supplied SV_GfxBuffer
  1063.     as the source for creating the destinaion graphics file.
  1064.  
  1065.     The structures still have to be freed the way they have been
  1066.     allocated : - self-created     : ...
  1067.             - SVL_GetGfxBuffer() : SVL_FreeResources(),
  1068.                        SVL_FreeHandle()
  1069.  
  1070.    INPUT(S)
  1071.  
  1072.     handle - a valid handle
  1073.     buffer - a valid SV_GfxBuffer pointer
  1074.     future - always NULL yet
  1075.  
  1076.    RESULT
  1077.  
  1078.     NULL or an adequate SVERR-Errorcode.
  1079.  
  1080.    WARNING
  1081.  
  1082.     Before V6 the documentation said under FUNCTION :
  1083.     "If also a valid Screen Pointer is supplied, the SV_GfxBuffer
  1084.      is ignored".
  1085.  
  1086.     There's no guarantee for that AND you never should supply
  1087.     TWO Sources for ONE Destination.
  1088.  
  1089.     GfxBuffer-Writing works since V6 with the supplied SVObjects
  1090.     and they do prefer GfxBuffers, NOT Screens.
  1091.     Screens have to be converted into GfxBuffers internally, before
  1092.     they can written, so GfxBuffers should take less memory ...
  1093.     Last not least : This function was broken upto V5, anyway.
  1094.  
  1095.    BUGS
  1096.  
  1097.     This function was broken from V3.x to V5.x !
  1098.  
  1099.    SINCE
  1100.  
  1101.     ... version 3 of the superview.library. (request V6+)
  1102.  
  1103.    SEE ALSO
  1104.  
  1105.     SVL_ReadGfxBuffer(), SVL_SuperWrite()
  1106.  
  1107. -----------------------------------------------------------------------------
  1108.  
  1109.    NAME
  1110.     SVL_DisplayGfxBuffer
  1111.  
  1112.    SYNOPSIS
  1113.  
  1114.     ULONG SVL_DisplayGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  1115.     D0    -$a8           A1        A2
  1116.  
  1117.                    ULONG future)
  1118.                    A3
  1119.  
  1120.  
  1121.    FUNCTION
  1122.  
  1123.     The combination SVL_ReadToGfxBuffer() and SVL_DisplayGfxBuffer()
  1124.     has the same effect as a call to SVL_SuperView().
  1125.     But note, that GfxBuffer-functions only work with Version 2
  1126.     SVObjects, while SVL_SuperView() also fits to Version 1 SVObjects.
  1127.     Internally, the result is the same, anyway.
  1128.  
  1129.     The difference is : Multiple displaying is possible
  1130.     (SVL_DisplayGfxBuffer(), SVL_CloseDisplay(), SVL_DisplayGfxBuffer(),
  1131.      ... and so on).
  1132.  
  1133.     The SV_GfxBuffer still has to be freed the way it has been
  1134.     allocated : - self-created     : ...
  1135.             - SVL_GetGfxBuffer() : SVL_FreeResources(),
  1136.                        SVL_FreeHandle()
  1137.  
  1138.    INPUT(S)
  1139.  
  1140.     handle - a valid handle
  1141.     buffer - a valid SV_GfxBuffer pointer
  1142.     future - always NULL yet
  1143.  
  1144.    RESULT
  1145.  
  1146.     NULL or an adequate SVERR-Errorcode.
  1147.  
  1148.    WARNING
  1149.  
  1150.     Only pass the ORIGINAL SV_GfxBuffer pointer to this functions
  1151.     (get it via SVL_GetGfxBuffer()) !
  1152.     Currently (V6.3) this Buffer pointer is not really passed through
  1153.     to the SVObjects : They always use the pointer, which they
  1154.     initialized while loading the picture.
  1155.     So if you pass other pointers, it would be as if you did not
  1156.     pass anything (this is what you actually do, but usually you do
  1157.     not recognize it).
  1158.     On the other hand, do NEVER set this pointer simply to NULL
  1159.     (thinking : it will be ignored, anyway), because it might be
  1160.     really used in future versions.
  1161.  
  1162.    BUGS
  1163.  
  1164.     This function was broken from V3.x to V4.x !
  1165.  
  1166.    SINCE
  1167.  
  1168.     ... version 3 of the superview.library.
  1169.  
  1170.    SEE ALSO
  1171.  
  1172.     SVL_ReadGfxBuffer(), SVL_SuperWrite()
  1173.  
  1174. -----------------------------------------------------------------------------
  1175.    Functions added with Version 6 :
  1176. -----------------------------------------------------------------------------
  1177.  
  1178.    NAME
  1179.     SVL_GetSVObjectList
  1180.  
  1181.    SYNOPSIS
  1182.  
  1183.     ULONG SVL_GetSVObjectList(struct SVObjectInfo **listhead)
  1184.     D0    -$ae          A1
  1185.  
  1186.    FUNCTION
  1187.  
  1188.     Creates a simplified list of all SVObjects (SubTypes), which
  1189.     may be used for read-only purposes until it has been freed
  1190.     via SVL_FreeSVObjectList.
  1191.  
  1192.    INPUT(S)
  1193.  
  1194.     listhead - a pointer to a SVObjectInfo structure pointer
  1195.  
  1196.    RESULT
  1197.  
  1198.     NULL or an adequate SVERR-Errorcode.
  1199.  
  1200.    BUGS
  1201.  
  1202.     -
  1203.  
  1204.    SINCE
  1205.  
  1206.     ... version 6 of the superview.library.
  1207.  
  1208.    SEE ALSO
  1209.  
  1210.     SVL_FreeSVObjectList
  1211.  
  1212. -----------------------------------------------------------------------------
  1213.  
  1214.    NAME
  1215.     SVL_GetSVDriverList
  1216.  
  1217.    SYNOPSIS
  1218.  
  1219.     ULONG SVL_GetSVDriverList(struct SVDriverInfo **listhead)
  1220.     D0    -$b4          A1
  1221.  
  1222.    FUNCTION
  1223.  
  1224.     Creates a simplified list of all SVDrivers, which
  1225.     may be used for read-only purposes until it has been freed
  1226.     via SVL_FreeSVDriverList.
  1227.  
  1228.    INPUT(S)
  1229.  
  1230.     listhead - a pointer to a SVDriverInfo structure pointer
  1231.  
  1232.    RESULT
  1233.  
  1234.     NULL or an adequate SVERR-Errorcode.
  1235.  
  1236.    BUGS
  1237.  
  1238.     -
  1239.  
  1240.    SINCE
  1241.  
  1242.     ... version 6 of the superview.library.
  1243.  
  1244.    SEE ALSO
  1245.  
  1246.     SVL_FreeSVDriverList
  1247.  
  1248. -----------------------------------------------------------------------------
  1249.  
  1250.    NAME
  1251.     SVL_FreeSVObjectList
  1252.  
  1253.    SYNOPSIS
  1254.  
  1255.     ULONG SVL_FreeSVObjectList(struct SVObjectInfo *listhead)
  1256.     D0    -$ba           A1
  1257.  
  1258.    FUNCTION
  1259.  
  1260.     Frees a list returned by SVL_GetSVObjectList.
  1261.  
  1262.     Pass the List-Header, not an entry !
  1263.  
  1264.    INPUT(S)
  1265.  
  1266.     listhead - a pointer to a SVObjectInfo structure
  1267.  
  1268.    RESULT
  1269.  
  1270.     NULL or an adequate SVERR-Errorcode.
  1271.  
  1272.    BUGS
  1273.  
  1274.     -
  1275.  
  1276.    SINCE
  1277.  
  1278.     ... version 6 of the superview.library.
  1279.  
  1280.    SEE ALSO
  1281.  
  1282.     SVL_GetSVObjectList
  1283.  
  1284. -----------------------------------------------------------------------------
  1285.  
  1286.    NAME
  1287.     SVL_FreeSVDriverList
  1288.  
  1289.    SYNOPSIS
  1290.  
  1291.     ULONG SVL_FreeSVDriverList(struct SVDriverInfo *listhead)
  1292.     D0    -$c0           A1
  1293.  
  1294.    FUNCTION
  1295.  
  1296.     Frees a list returned by SVL_GetSVDriverList.
  1297.  
  1298.     Pass the List-Header, not an entry !
  1299.  
  1300.    INPUT(S)
  1301.  
  1302.     listhead - a pointer to a SVDriverInfo structure
  1303.  
  1304.    RESULT
  1305.  
  1306.     NULL or an adequate SVERR-Errorcode.
  1307.  
  1308.    BUGS
  1309.  
  1310.     -
  1311.  
  1312.    SINCE
  1313.  
  1314.     ... version 6 of the superview.library.
  1315.  
  1316.    SEE ALSO
  1317.  
  1318.     SVL_GetSVDriverList
  1319.  
  1320. -----------------------------------------------------------------------------
  1321.